Release 10.1A: OpenEdge Development:
Progress Dynamics Administration

Setting up new databases with the DCU

The main focus of the DCU is setting up the Repository database. Therefore, it is simple to extend a DCU session to also set up your application database as well. Every deployment should be able to create a new database. You can customize a deployment to create a new application database as follows:

  1. Create a custom session type and generate a configuration file for it.

  2. Create a custom DCU driver file for the new session type.

  3. Add a page to the DCU driver file to collect install information.

  4. Add a node for the new database in the DCU driver file.

  5. Create a database creation upgrade file for your application database.

Creating a custom session type

It is good practice to have a separate session type for each application you deploy. The Session Type Control enables you to extend existing session types to create customized ones.

To create a new DCU session type:
  1. In the Session Type Maintenance window, choose Basic DCU ProgressSetup.

  2. Choose Add record to create a new session type. The new session type automatically extends ProgressSetup.

  3. Name the new session type and save it. For example, you might specify a session type name for the DynSports sample application as DynSportsSetup.

  4. Create overrides for the ProgressSetup session properties under the new session type. For example:

    5. Session property
    Sample value 
    setup_type 

    DynSportsSetup 

    setup_type_file 

    db/dynsports/dfd/DynsportsSetup01.xml 

    window_title 

    DynSports Configuration Utility

  5. Generate a configuration file using your new session type. By convention, the filename is application-namesetup.xml. For example, dynsportssetup.xml.

By changing the DCUSETUPTYPE and ICFCONFIG parameters to your new session type and configuration file, you can now override the DCU with your custom deployment.

Creating a custom DCU driver file

Your custom configuration uses the DCU driver file that you named in the setup_type_file session property. Your next step is to create that file. While you could build one from scratch, you can also alter a standard DCU driver file.

To create a custom DCU driver file:
  1. Save a copy of the latest standard DCU driver file to the directory and filename specified in the setup_type_file session property of your custom session type.

  2. Change the <setup> node to your custom session type. For example:

    3. <setup SetupType="DynSportsSetup">

  3. In the Welcome page description, change the contents of the editor control’s <DefaultValue> to reflect your application. For example, you might change the standard text to the following for the DynSports application:

    4. Welcome to the DynSports Configuration Utility. 
This process will set up the databases that are required to run the 
current version of DynSports. 
Choose the Next button to start this process. Choose Cancel to leave 
without modifying anything.

  4. You can also alter the settings of the following nodes to change the appearance of the DCU to reflect your own application:

    • <ImageLowRes>
    • <ImageHiRes>
    • <IconFile>

If you run your custom DCU session now, it brings up the altered Welcome page. It cannot install your application database yet. It needs to gather path information on where the database files are located.

Adding a page to the DCU

The DCU needs to know where the source files for your application database are. One of the existing DCU pages, the ICFDB Parameters page, captures this type of information for the Repository. You can reuse it to capture the information for your application database.

The page you are reusing supports upgrading existing databases, as well as creating new databases. This section concentrates on those parts of the page that build a new database. Using the DCU for upgrades is discussed in the "Upgrading existing databases with the DCU" section.

To add a new page to the DCU driver file:
  1. In your DCU driver file, copy the GetICFDBParams page description. It begins with the <page Name="GetICFDBParams"> node and ends with the next </page> node.

  2. Paste a copy of the page description before the Status page description.

  3. Change the page name, title, and page group to reference your application. For example, the beginning of the DynSports Parameters page description would look like this:

    4. <page Name="GetDynSportsParams"> 
  <Title>DynSports Parameters</Title> 
  <Group>DynSports</Group>

  4. Change the checkForDB action to use the logical name of you application database. For the DynSports example, it would be the following:

    5. <action> 
  <Event>INITIALIZE</Event> 
  <Action>checkForDB</Action> 
  <ActionParam>DynSports</ActionParam> 
</action>

  5. Set the Back button to go to the ICFDB Parameters page. For the DynSports example, it would be the following:

    6. <control> 
  <Type>Button</Type> 
  <Panel>Yes</Panel> 
  <Label>&amp;Back</Label> 
  <Name>Back</Name> 
  <Justify>Right</Justify> 
  <action> 
    <Event>CHOOSE</Event> 
    <Action>gotoPage</Action> 
    <ActionParam>GetICFDBParams</ActionParam> 
  </action> 
</control>

    Note: There are several paths through the ICFDB pages. With conditional processing, you could have the DCU return to the page from which the user came.

  6. Set the Next button to go to the Status page in the Wizard sequence.

    7. You do not need to modify the other actions that occur when the user chooses the Next button. The screenScrape action records the values from the objects. The connectDatabase and verifyDBVersion actions are conditional and will not occur during the build of a new database.

  7. Change the text in the editor’s default value to describe your application database.

  8. Change the remaining ICFDB references to refer to your application database.

Your customized DCU can now gather the information on where to find the build files for your application database. The last thing you need is an upgrade file that tells how to use the files.

Adding a database node

The DCU driver file needs a node for each database in the deployment.

To add a node for your application database, copy the ICFDB node and modify the values for your application database. For example, a DynSports database node might look like this:

 

<database> 
  <DBName>DynSports</DBName> 
  <VersionSeq>seq_dynsports_dbversion</VersionSeq> 
  <MinimumVersion>010000</MinimumVersion> 
  <ConnectParams>-1</ConnectParams> 
  <DBDir>#path_db#\dynsports\dynsports.db</DBDir> 
  <DBDump>#path_src#\#dynamics_rootname#\db\dynsports\dump</DBDump> 
  <patch PatchLevel="0" DBBuild="Yes" 
      NodeURL="dynsports/dfd/dynsportsbuild.xml"/> 
</database>

Creating a database creation upgrade file

As before, the simplest method for creating the upgrade file is to copy and customize the standard file.

To create a database creation upgrade file:
  1. Copy and rename the Repository creation upgrade file, icfdbbuild.xml. For example, the DynSports file would be dynsportsbuild.xml.

  2. Change the full schema definition filename to the one for your application database. For the DynSports example, it might look like the following:

    3. <patchstage UpdateStage="Delta"> 
  <Program> 
    <FileType>df</FileType> 
    <FileName>dynsports/dfd/dynsportsfull.df</FileName> 
    <Description>Applying Full DynSports DB Schema</Description> 
    <Rerunnable>no</Rerunnable> 
    <NewDB>yes</NewDB> 
    <ExistingDB>no</ExistingDB> 
    <UpdateMandatory>yes</UpdateMandatory> 
  </Program> 
</patchstage>

  3. In the next patch stage, remove the program node for the Setting Site Number program. That program is specific to the Repository.

Your custom DCU can now create a new application database in addition to creating and upgrading the Repository.

Copyright © 2005 Progress Software Corporation
 www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095